home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Games Collection 1 / software vault.zip / software vault / CDR10 / SPX20.ZIP / SPX_DOC.ZIP / SPX_FNC.DOC < prev    next >
Text File  |  1993-09-15  |  11KB  |  377 lines
  1. { SPX Library Version 2.0  Copyright 1993 Scott D. Ramsay }
  2.  
  3.  SPX_FNC  contains general functions and procedures that are used
  4. by most of the units.
  5.  
  6. ───────────────────────────────────────────────────────────────────────────
  7. function sgn(h:integer):integer;
  8.  
  9.   Returns -1 if H is less than zero
  10.            1 if H is greater than zero
  11.            0 if H is equal to zero
  12. ───────────────────────────────────────────────────────────────────────────
  13. function strint(s:string):longint;
  14.  
  15.   converts a four character string to a longint value;
  16.  
  17.   The characters are repesented at hi and lo byte values of the longint.
  18.  
  19.   EXAMPLE:
  20.  
  21.     var
  22.       s : string;
  23.       l : longint;
  24.     begin
  25.       s := 'AT';
  26.       l := strint(s); { l := 21569  or $00005441 }
  27.     end;
  28.  
  29. ───────────────────────────────────────────────────────────────────────────
  30. function intstr(l:longint):string;
  31.  
  32.    converts a longint to a four character string.
  33.  
  34.    EXAMPLE:
  35.  
  36.      var
  37.         s : string;
  38.         l : longint;
  39.      begin
  40.        s := intstr(21569);  { s := 'AT'#0#0; }
  41.      end;
  42.  
  43. ───────────────────────────────────────────────────────────────────────────
  44. function ups(s:string):string;
  45.  
  46.    returns S in all uppercase letters.
  47.  
  48. ───────────────────────────────────────────────────────────────────────────
  49. function st(h:longint):string;
  50.  
  51.    converts H to a string
  52.  
  53.    EXAMPLE:
  54.  
  55.       var
  56.          s : string;
  57.       begin
  58.          s := st(123);   { s := '123';
  59.       end;
  60.  
  61. ───────────────────────────────────────────────────────────────────────────
  62. function compare(s1,s2:string):boolean;
  63.  
  64.    Compares two strings returns true if they are equal up to the length
  65.    of S1.
  66.  
  67.    EXAMPLE:
  68.  
  69.        compare('SPXLIB','SPX')  returns FALSE
  70.        compare('SPX','SPXLIB')  returns TRUE
  71.  
  72. ───────────────────────────────────────────────────────────────────────────
  73. function dtcmp(var s1,s2;size:word):boolean;
  74.  
  75.    Same as function CMP.   Here for compatibility
  76.  
  77. ───────────────────────────────────────────────────────────────────────────
  78. function cmp(var s1,s2;size:word):boolean;
  79.  
  80.    Compares to variables of unknown types.
  81.  
  82.    S1,S2:   objects of any type to compare
  83.    SIZE:    size of objects
  84.  
  85.    Returns true if the bytes within S1 and S2 are equal
  86.  
  87. ───────────────────────────────────────────────────────────────────────────
  88. function lz(i,w:longint):string;
  89.  
  90.    Converts a longint to a string with leading zeros.
  91.  
  92.    I:    Integer to convert
  93.    W:    Number of spaces to place zeros
  94.  
  95.    EXAMPLE:
  96.  
  97.       var
  98.         s : string;
  99.       begin
  100.         s := lz(1234,7);  { s := '0001234'; }
  101.       end;
  102.  
  103. ───────────────────────────────────────────────────────────────────────────
  104. function vl(h:string):longint;
  105.  
  106.    converts a string to a longint value
  107.  
  108.    H:  string to convert
  109.  
  110. ───────────────────────────────────────────────────────────────────────────
  111. function spaces(h:integer):string;
  112.  
  113.    Creates a string with H number of spaces
  114.  
  115.    EXAMPLE:
  116.  
  117.        s := spaces(10); { s := '          '; (* ten spaces *) }
  118.  
  119. ───────────────────────────────────────────────────────────────────────────
  120. function repstr(h:integer;ch:char):string;
  121.  
  122.    Creates a string with H number of the character ch.
  123.  
  124.  
  125.    EXAMPLE:
  126.  
  127.       s := repstr(10,'A');  { s := 'AAAAAAAAAA'; }
  128.  
  129. ───────────────────────────────────────────────────────────────────────────
  130. function ifix(var a:integer;min,max:integer):boolean;
  131.  
  132.    Sets an integer to the range min..max.
  133.  
  134.    A:     Value to change
  135.    MIN:   Minimum value A can be
  136.    MAX:   Maximum value A can be
  137.  
  138.    Returns TRUE if the variable was changed.
  139.  
  140.    EXAMPLE:
  141.  
  142.      {$X+ }  { enable extended syntax }
  143.  
  144.      var
  145.        a,b,c     : integer;
  146.        modified,
  147.        didChange : boolean;
  148.      begin
  149.        a := -10;
  150.        b := 112;
  151.        c := 50;
  152.        didChange := ifix(a,0,100);
  153.        modified := ifix(c,0,100);
  154.        ifix(b,0,100);
  155.  
  156.          { didChange := TRUE }
  157.          { modified := FALSE }
  158.          { a := 0   }
  159.          { b := 100 }
  160.          { c := 50  }
  161.      end;
  162.  
  163. ───────────────────────────────────────────────────────────────────────────
  164. function rfix(var a:real;min,max:real):boolean;
  165.  
  166.   Sets a real to the range min..max.
  167.  
  168.    A:     Value to change
  169.    MIN:   Minimum value A can be
  170.    MAX:   Maximum value A can be
  171.  
  172.    Returns TRUE if the variable was changed.
  173.  
  174.    EXAMPLE
  175.        See function ifix
  176. ───────────────────────────────────────────────────────────────────────────
  177. function anything(s:string):boolean;
  178.  
  179.    Returns TRUE if the S is not an empty string or if any of
  180.      the characters in S is in the range #32..#255 (ascii)
  181.  
  182. ───────────────────────────────────────────────────────────────────────────
  183. function exist(f:string):boolean;
  184.  
  185.    Returns TRUE if the file exist on disk
  186.  
  187.    F:  The file to check.  Can have full file spec.
  188. ───────────────────────────────────────────────────────────────────────────
  189. function TPerror(errorcode:integer) : string;
  190.  
  191.    Returns an Turbo Pascal error string
  192.  
  193.    ERRORCODE:   value generated by the funciton IOresult
  194.  
  195. ───────────────────────────────────────────────────────────────────────────
  196. procedure funpad(var s:string);
  197.  
  198.    Removes all leading spaces from the string S
  199.  
  200. ───────────────────────────────────────────────────────────────────────────
  201. procedure unpad(var s:string);
  202.  
  203.    Removes all trailing spaces from the string S
  204.  
  205. ───────────────────────────────────────────────────────────────────────────
  206. procedure munpad(var s:string;b:byte);
  207.  
  208.    Cuts string S to length B.  Then removes all trailing charaters
  209.     that are in the range #0..#31.
  210.  
  211. ───────────────────────────────────────────────────────────────────────────
  212. function fpad(s:string;h:integer):string;
  213.  
  214.    Returns the string S with length H by adding trailing spaces
  215.    if nessasary.
  216.  
  217. ───────────────────────────────────────────────────────────────────────────
  218. procedure pad(var s:string;h:integer);
  219.  
  220.   Same as fpad.  Changes string S to length H by adding trailing spaces
  221.   if nessasary.
  222.  
  223. ───────────────────────────────────────────────────────────────────────────
  224. procedure fix(var s:string;h:string);
  225.  
  226.   Adds an extension to the file name S if one does not exist.
  227.  
  228.   S:  String to check for extenstion
  229.   H:  extension to add
  230.  
  231.   EXAMPLE:
  232.  
  233.     s1 := 'mypic';
  234.     s2 := 'mypic2.';
  235.     s3 := 'mypic3.dog';
  236.     s4 := 'mypic4.pcx';
  237.  
  238.     fix(s1,'.PCX');  { s1 := 'mypic.PCX'  }
  239.     fix(s2,'.PCX');  { s2 := 'mypic2.'    }
  240.     fix(s3,'.PCX');  { s3 := 'mypic3.dog' }
  241.     fix(s4,'.PCX');  { s4 := 'mypic.pcx'  }
  242.  
  243. ───────────────────────────────────────────────────────────────────────────
  244. procedure fixh(var s:string);
  245.  
  246.   Converts all characters in S that are in the range #0..#31 to spaces
  247.  
  248. ───────────────────────────────────────────────────────────────────────────
  249. function range(x,y,x1,y1,x2,y2:integer) : boolean;
  250.  
  251.   Returns TRUE if the point (x,y) is in the rectangle (x1,y1,x2,y2)
  252.  
  253. ───────────────────────────────────────────────────────────────────────────
  254. function rrange(x,y,x1,y1,x2,y2:real) : boolean;
  255.  
  256.   Returns TRUE if the point (x,y) is in the rectangle (x1,y1,x2,y2)
  257.  
  258. ───────────────────────────────────────────────────────────────────────────
  259. function between(x,x1,x2:longint):boolean;
  260.  
  261.   Returns TRUE if X is between X1 and X2
  262.  
  263. ───────────────────────────────────────────────────────────────────────────
  264. function fspaces(s:string;skip:byte):string;
  265.  
  266.   Returns a string portion in S delimited by spaces.  Returns an empty
  267.   string if one is not found.
  268.  
  269.   S:     string to search
  270.   SKIP:  number of strings to skip
  271.  
  272.   EXAMPLE:
  273.  
  274.      s := 'Now is the time for all good men to';
  275.  
  276.      writeln(fspaces(s,0));   { outputs 'Now'   }
  277.      writeln(fspaces(s,3));   { outputs 'time'  }
  278.      writeln(fspaces(s,9));   { outputs ''      }
  279.  
  280. ───────────────────────────────────────────────────────────────────────────
  281. function GetPtr(p:pointer;offset:longint):pointer;
  282.  
  283.    Creates a new pointer at P+offset.  Adjusts for segment boundries.
  284.    Returns the new pointer location.  Note: offset MUST be positive or zero.
  285.  
  286.    P:        pointer to adjust
  287.    OFFSET:   offset for the pointer (in bytes)
  288.  
  289.    EXAMPLE:
  290.  
  291.    var
  292.      p : pointer;
  293.  
  294.    p := GetPtr(SomePointer,88000);
  295.  
  296.    { p points to 88000 bytes past SomePointer }
  297.  
  298. ───────────────────────────────────────────────────────────────────────────
  299. function sar(value:integer;shift:byte):integer;
  300.  
  301.   Shift arithmetic right.  Same as SHR but maintains the signed (hi) bit.
  302.  
  303.   VALUE: integer value to shift.
  304.   SHIFT: bits to shift
  305.  
  306.   note: I don't know why Borland never added this operator! I hate
  307.      to type the typecast each time. ( integer(value shr shift) )
  308.  
  309.   EXAMPLE:
  310.  
  311.      writeln(sar(10,1));   { outputs   5 }
  312.      writeln(sar(-10,1));  { outputs  -5 }
  313.  
  314.  
  315. ───────────────────────────────────────────────────────────────────────────
  316. function sal(value:integer;shift:byte):integer;
  317.  
  318.   Shift arithmetic left.  Same as SHL but maintains the signed (hi) bit.
  319.  
  320.   VALUE: integer value to shift.
  321.   SHIFT: bits to shift
  322.  
  323.    EXAMPLE:
  324.  
  325.      writeln(sal(10,1));   { outputs   20 }
  326.      writeln(sal(-10,1));  { outputs  -20 }
  327.  
  328. ───────────────────────────────────────────────────────────────────────────
  329. function ptr2hex(p:pointer):string;
  330.  
  331.   Converts a pointer to a string in hexadecimal format
  332.  
  333.   P: pointer to convert
  334.  
  335.   p := ptr($a000,20);
  336.   writeln(ptr2hex(p));   { outputs   A000:0014 }
  337.  
  338. ───────────────────────────────────────────────────────────────────────────
  339. function word2hex(w:word):string;
  340.  
  341.   Converts a word value to hexadecimal format
  342.  
  343. ───────────────────────────────────────────────────────────────────────────
  344. function byte2hex(b:byte):string;
  345.  
  346.   Converts a byte value to hexadecimal format
  347.  
  348. ───────────────────────────────────────────────────────────────────────────
  349. procedure atexit(proc:QuitProc);
  350.  
  351.   Same as the function in C.  Calls a quit procedure at exit.  Can use
  352.    many times. Chains multiple procedures.  At the exit of the program
  353.    the procedure are called in a LIFO fashion.  (Last in-First out) The
  354.    last atexit procedure is the first one to be called.
  355.  
  356.   PROC:  procedure to call at the end of the program.  Must be declared
  357.     as a far procedure.
  358.  
  359.   EXAMPLE:
  360.  
  361.      Uses spx_fnc;
  362.  
  363.      {$F+ }
  364.      procedure cleanup;
  365.      begin
  366.        { do my clean up routines here }
  367.      end;
  368.  
  369.      procedure returnToTextMode;
  370.      begin
  371.        textmode(c80);
  372.      end;
  373.  
  374.      begin
  375.        atexit(cleanup);
  376.        atexit(returnToTextMode);
  377.      end.